FishMarket 1.0/FishMarket v1.0.iso/fishies/476-500/disk_500/wiconify/wiconify.doc

Text File | 1992-05-06 | 81KB | 1,644 lines

OVERVIEW:

wIconify is an Intuition enhancement program that allows you to "iconify" any
Intuition window on any screen.  Iconified windows become small icons on at
the bottom of the screen, and they can be opened again by double-clicking
them, and operate in a fashion similar to Workbench icons.  Smart-refresh
windows can be turned into simple-refresh windows during iconification in
order to save memory.  wIconify also allows entire screens to be iconified,
though no memory savings occurs by doing this.

Past versions of wIconify only allowed windows on the Workbench screen to be
iconified, but the current version works for windows on ANY screen.
wIconify also includes features that allow you to turn any screen into "a
workbench screen"; that is, windows that normally open on the Workbench
screen can be redirected to open on any screen whatever.  Furthermore,
wIconify allows you to open new screens easily for just this purpose.

When used with its companion utility, wIconSetter, wIconify allows you to
customize the icon imagery for specific windows so that your favorite
programs can have distinctive icons.  wIconSetter provides a number of
methods of producing icon imagery, including converting Workbench .info
files to wIconSetter icons.

Finally, wIconify provides a programmer's interface that includes all the
procedures necessary to create and manipulate icons from within a user-
written program.  Several examples are provided, including an icon clock
with hands that change as time passes.


INSTALLING AND REMOVING WICONIFY:

To install wIconify, place the WICONIFY command in youre C: directory (or in
your current command PATH), and WICONIFY-HANDLER in the L: directory.
Alternatively, create a directory named wIconify on you system disk, place
WICONIFY and WICONIFY-HANDLER in that directory, and use the PATH ADD command
to include this directory in your command path (see the CLI documentation
for information on the command path).

Now use the ASSIGN command to assign the name WICONIFY: to the directory
where you put the WICONIFY command (usually C: or the wIconify directory).
You probably want to include this command in the startup-sequence found in
the S: directory (see the Workbench 1.3 or 2.0 documentation for information
on the startup-sequence file).

To start wIconify, simply issue the command

    1> wIconify [initfile]

where 'initfile' is the name of an optional initialization file that can be
used to customize wIconify (see CUSTOMIZING WICONIFY below).  If no file is
specified, wIconify will look for WICONIFY:wIconify.init or S:wIconify.init
as the initialization file.

You will probably want to add the WICONIFY command to your startup-sequence.
If so, you should be aware that its position in your startup-sequence may be
important to the correct operation of wIconify (see WICONIFY AND THE STARTUP
SEQUENCE and INTERACTION WITH OTHER PROGRAMS below for more information).

There is no need to RUN wIconify, as wIconify will create a new process for
the wIconify-Handler automatically.

To stop wIconify once it is running, simply issue the wIconify command
again, or use the END menu item of wIconify's ICON menu.  There are some
important subtlties involved with ending wIconify which you should
understand; see ENDING WICONIFY below for details.


WICONIFYING WINDOWS:

Once wIconify is running, you should be able to iconify any window on any
screen.  To do so, select the window you want to iconify by clicking the
left button, and, while holding down the left mouse button, press and release
the right mouse button.  This is called a "left-right" click.  It may feel a
little awkward at first, but it will become natural very quickly.  Note that
this operation is similar to the extended menu selection process already
defined by Intuition in which you select multiple menu items by clicking the
left button while you have a menu open with the right button (this is called
a right-left click).  The button or key-stroke that iconifies a window can be
customized using the wIconify.init file (see CUSTOMIZING WICONIFY below).

When you left-right click in a window, it will disappear and be replaced
by a small icon in the lower-left of the screen on which the window was
open.  Note that the program controlling the window is still running, and
can update the window even while it is iconified.  Also note that
SMART_REFRESH windows will take up MORE memory when they are iconified than
when they are visible.  This can be altered (for a price); see WICONIFY AND
SMART_REFRESH WINDOWS below.

The icon will have the same name as the window title so that you can
identify the window belonging to each icon.  To restore a window from its
iconified form, click on the window's icon and select the OPEN item from the
ICON menu, or simply double-click on the icon you want to open.  The window
will be restored and its icon removed.

By default, all window icons use the same imagery.  This image can be
customized using the initialization file (see CUSTOMIZING WICONIFY below).
If you use the companion program, wIconSetter, you can use custom icons for
individual windows.  wIconSetter is easy to use, and makes wIconify much more
visually appealing; its use is strongly recommended.  See the wIconSetter
documentation for more information.

Window icons can be manipulated in a fashion very similar to that of Workbench
icons:  you select one by clicking on it; you select (or unselect)
additional icons by clicking them while holding down the SHIFT key; you
can drag them from one location to another on screen; finally, you can open
icons by double-clicking them.

In addition to these operations, the ICON menu includes items that allow
you to OPEN iconified windows (restore their windows and remove the icons),
CLOSE icons (close the windows associated with the icons), LOCK and UNLOCK
icons (prevent them from being moved from their current locations), CLEAN UP
the icons ("snap" them to the grid), ORGANIZE the icons (move them all down
to the bottom of the screen again), and OPEN ALL icons.  See the WICONIFY
MENUS section below for more details.

Normally, when you open an icon, its last position on screen is retained so
that when you iconify the window again, its icon will appear where it was
before, unless some other icon already is occupying that spot.  Thus you can
move an icon to a selected location and expect it to stay there without
having to use the LOCK command.

Note that programs that use the wIconify programmer's interface may specify
that their icons are locked, or that they can not be closed, or that they do
not save their last positions, or that their windows can NOT be iconified, so
some icons may not respond as the default window icons do.


ICONIFYING SCREENS:

In addition to being able to iconify windows, wIconify gives you the ability
to iconify entire screens, that is, the screen itself will disappear and
will be replaced by an icon on the Workbench screen.  To do so, simply left-
right click in the wIconify backdrop window on the screen you want to
iconify (that is, attempt to iconify the wIconify window).  The programs using
the screen will still be running, and will be able to continue to use and
update the windows on that screen, but they no longer will be visible.

To get the screen back, double-click on the screen's icon on the Workbench
screen.  The screen should reappear.  By default, screen icons have a
different image from window icons, so it should be easy to distinguish them
on the Workbench.  You can customize the screen icon using the
intitialization file (see CUSTOMIZING WICONIFY below).

Screen icons can be manipulated just like any other icon; see ICONIFYING
WINDOWS for more details on icons and their properties.  Since screen icons
only appear on the Workbench screen, it is not possible to iconify the
Workbench screen itself.

The memory in use by a screen is still in use when that screen is iconified,
so there is no memory saved by iconifying a screen.  It is simply a method
of organizing your work area better.


ICON LAYOUT:

When windows or screens are iconified, their icons appear at the bottom of
the screen starting at the lower left-hand corner.  As new icons appear,
they are placed to the right.  This makes it easy to shrink the size of a
window slightly, if necessary, to get access to the icons (or you could just
iconify the window that's in the way).  Alternate columns of icons are
staggered (slightly lower) so that long names do not over-write one-another.

Once an icon appears on the screen, you can, of course, drag the icon to a
new location.  Under usual conditions, the icon will retain this position
after it is opened and re-iconified, so you should be able to place an icon
where you want it to be, and expect it to stay there.

Icons will not be placed on top of other icons (unless you drag them their
yourself, or unless they are LOCKED), so the screen layout should be
realtively easy to view.  If it becomes messy, however, there are two menu
items that can help.

The CLEANUP item of the ICON menu will cause all selected icons to be
"snapped" to the icon grid.  That is, they move to the closest (unused) grid
position to their current location.  If no icons are selected, then all the
icons on the screen will be cleaned up.  Icons with the LOCKED or NOORGANIZE
flag set will be unaffected by the CLEANUP command, however.

The ORGANIZE item of the ICON menu will cause all icons to "fall" to the
bottom of the screen; that is, any icons that have been moved away from the
bottom will be put back along the bottom.  This puts all icons into their
"natural" positions on the screen.  As before, and icons marked as LOCKED
or with the NOORGANIZE flag set are not affected by ORGANIZE.

Currently, there is no method for customizing the initial positions of
icons, but a future enhancement may provide the ability to specify that
icons should form along the right-hand edge, for example.


WICONIFY AND SMART_REFRESH WINDOWS:

When a window is covered by another window, and then becomes uncovered, the
portion of the window that was obscured must be refreshed to redisplay the
information that it contained.  Intuition provides windows with a number of
refresh methods, the most common being SMART_REFRESH and SIMPLE_REFRESH.
The first of these is the easiest and fastest to use, but the most memory-
intensive:  when a part of the window is covered, Intuition copies the
obscured portion to an off-screen memory area and when the window is
uncovered again, Intuition restores the contents of the window automatically
from the saved data.  The program that owns the window never even knows that
the window was partially covered.  The restoration of uncovered windows is
very fast, but if large portions of large windows become covered, this can
use up a lot of CHIP memory.

The second refresh method (SIMPLE_REFRESH) takes up no additional memory,
but requires special programming to implement.  In this case, when a portion
of window is covered then uncovered, Intuition informs the program that part
of its window must be restored, and then the program is required to redraw
the information into the window itself.  This usually takes longer,
depending on the amount of data to be restored, but has the advantage of
requiring no additional memory regardless of the size of a window or the
amount of it that is covered.  There are many situiations when this is an
appropriate refresh method; for example, if a window contains only text (no
graphics), as in a terminal communications program, it takes far less space
to store the contents of the window as ASCII text than as a bit-mapped image.

In a nutshell, SMART_REFRESH windows save in program complexity but require
more memory when covered, while SIMPLE_REFRESH windows require more
programming, but no additional memory.  Most programs use SMART_REFRESH
windows because they are less complicated and operate faster; for example,
the CLI windows are SMART_REFRESH even though they usually include only
textual data.

wIconify iconifies a window by pushing it behind its own backdrop window,
thus covering up the window completely.  For SIMPLE_REFRESH windows, this is
no problem, but this forces SMART_REFRESH windows to take up the maximum
amount of memory (the entire window is copied to memory off-screen).  For
example, a full-sized CLI window, when iconified, will take up the same
amount of memory as the screen itself.  The effect of this is that
SMART_REFRESH windows typically use up MORE memory when iconified than when
displayed.  This is unfortunate, but practically unavoidable.

Under certain circumstances, however, this behavior can be changed.
wIconify provides a method by which you can specify that SMART_REFRESH
windows should be treated as SIMPLE_REFRESH windows when they are
iconified:  if you hold down the left ALT key (called the change-refresh key)
when you iconify the window, wIconify will convert the refresh type of the
window to SIMPLE_REFRESH while it is iconified (it will be restored to
SMART_REFRESH when it is opened again).  This means you may save memory
when you iconify the window.  (The change-refresh key can be changed using
the initialization file; see CUSTOMIZING WICONIFY below).

Unfortunately, there is a catch.  Since the data in SIMPLE_REFRESH windows
is lost when they are covered (the program itself must refresh it), and
since programs that use SMART_REFRESH windows do not expect to have to
refresh their windows, when you restore a window that has been changed to a
SIMPLE_REFESH window, its contents will have been lost.  Intuition will
redraw the border and usually its gadgets (drag bar, depth gadgets, etc.),
but any other data in the window will be lost.  In particular, it may be
impossible to tell where buttons or other "active areas" of the window are
located!  This may be OK for CLI windows, where the data in the window can
be lost without harm, but it may be devastating for programs that have no
other copy of the data except for what's in the window itself (art programs,
for example).

The moral is, use the change-refresh key with care.  It can be a big help
when you need to save memory, but it can lose information with no hope of
recovery!


WICONIFY AND THE WORKBENCH WINDOW:

In version 1.3 and earlier versions of the Workbench, the Workbench program
used a backdrop window on the Workbench screen in order to display and
maintain the Workbench icons.  For this reason, past versions of wIconify
"hooked into" this workbench window in order to place additional icons on
the screen.  This may have looked good, but was somewhat unreliable in
practice, and took considerable and complicated coding to accomplish.

In version 2.0 of the Workbench software, it appears that the Workbench
program will use a standard (non-backdrop) window with drag bar, sizing
gadgets, and other standard Intuition accoutrements.  It seems
inappropriate, then, for wIconify to continue to hook into this window, so
the current version of wIconify opens its own backdrop window instead.

This is fine for version 2.0, but what about those of us who still use
version 1.3, where the workbench still has its own backdrop window?  The
Workbench backdrop window will cover up the wIconify window so that it is
very inconvenient to get at the window icons.  The solution is actually very
simple:  wIconify converts the Workbench backdrop window into a non-backdrop
window and adds the standard gadgets.  Take care, however, since this means
that the Workbench window will be smaller.  Although the Workbench will not
move icons outside the visible area of the window itself, you can move them
there yourself by shrinking the size of the window.  There is no way to get
to these icons without enlarging the window again.

In order to take advantage of this feature of wIconify, you must start
wIconify BEFORE loading the Workbench; that is, the wIconify command must
come before the LoadWB command in your startup sequence.  wIconify will not
modify the Workbench window if it is already open.


WICONIFY AND PROGRAM SCREENS

Whenever a new screen opens, wIconify attempts to create a backdrop window
on that screen.  This is were the icons for that screen will be displayed
when windows become iconified.  It also provides you with the wIconify menu
bar on each screen (when the backdrop window is the active one).

The backdrop window may provide a number of complications, however.  Some
programs open their own backdrop windows (art programs for example) which
usually are as large as the screen itself.  Such windows will completely
obscure the wIconify backdrop window, making it impossible to see the icons
or even activate the wIconify window to get at its menu bar.

The best solution is to iconify the backdrop window that is in the way.
This will give you ready access to the wIconify backrop window.  If the
window is a smart-refresh window, however, this may be inappropriate since
it would take up a lot of memory when iconified.

Another solution is to press the "activation key" which tells wIconify to
activate its backdrop window on the current screen.  Usually, this is the
F1 function key with SHIFT held down, but it can be changed using the
initialization file (see CUSTOMIZING WICONIFY below).  This at least gives
you access to the wIconify menus, although you still will not be able to see
the wIconify backdrop window.

The pressence of additional backdrop windows (i.e., the wIconify backdrop
window) may cause trouble for some programs.  For example, a program that
draws directly into the screen's RastPort rather than into its own backdrop
window as the Intuition guide suggests, will draw right over top of the
icons provided by wIconify.  More severe difficulties also are possible;
some badly-behaved programs may even crash the system due to the presence of
the wIconify backdrop window.

In this case, you will want to tell wIconify NOT to open a backdrop window
on these screens.  You can do so through the IGNORE_SCREEN command in the
wIconify initialization file (see CUSTOMIZING WICONIFY below for details).
Any screens specified by an IGNORE_SCREEN command will be ignored by
wIconify.  That is, wIconify will not open a backdrop window on it.  Of
course, this also means that you will not be able to iconify any windows on
that screen either, nor will you be able to iconify the screen itself;
wIconify will not re-route workbench windows to this screen, or affect it in
any way.

If for any reason wIconify fails to be able to open a backdrop window on a
newly created screen (for example, there is not enough memory), then
wIconify will treat the screen as an ignored screen as described above.


SCREEN MANAGEMENT WITH WICONIFY:

In addition to its ability to iconify windows and screens, wIconify
a provides number of screen-management functions, as described below:

Some programs (particulary older software) do not provide access to their
screen's depth gadgets, which makes it very inconvenient to have more than
one screen open while they are running.  wIconify provides SCREEN TO_FRONT
and SCREEN TO_BACK menu items which can be used to depth arrange any screen
with a wIconify backdrop window.

The ICONIFY menu item in the SCREEN menu causes the current screen to become
iconified.  This is useful on screens where you do not have easy access to the
wIconify backdrop window (in order to left-right click it).

wIconify gives you the ability to toggle the title bar on or off on any
screen (wIconify error messages appear here, but some screens don't have
their screen title bars showing).

More importantly, however, wIconify gives you the ability to turn any screen
into a Workbench screen, that is, a screen that can be shared by windows
from many different programs.  Normally, a window that does not specify a
custom screen will be opened on the Workbench screen.  wIconify lets you
redirect these windows to any screen.  There are a number of features that
control this aspect of wIconify.

First, the OPEN_WINDOWS submenu of the SCREEN menu controls the screen on
which workbench windows will be opened.  There are three choices:

    ACTIVE_SCREEN       Open windows on the currently active screen

    CURRENT_WB          Open windows on the screen currently marked as
                        the Workbench screen via the MAKE_WB menu item

    REAL_WB             Open windows on the real Workbench screen

The first of these is the default; new windows will appear on whichever
screen you are using.  Sometimes this is not the most convenient method,
however, particularly if you must give a command on another screen in order
to open the window you want to appear on the current screen.

In this case, the second option might be more appropriate.  Using this method,
you can mark a screen as the one you want to use, then select some other
screen to give one or more commands that usually open windows on the
Workbench screen; all these windows will open on the screen you have marked
as the WB screen via the MAKE_WB menu item.  This is particularly convenient
if you are using wIconify as part of your startup sequence and you want
windows to be moved to other screens as your machine is booting (see WICONIFY
AND THE STARTUP-SEQUENCE below).  The WB_TO_FRONT menu item will bring the
current WB screen to the front of the display.  If you select MAKE_WB, the
screen becomes the current WB screen, and CURRENT_WB mode is selected
automatically.

Finally, if you do not want wIconify to change the screens where windows are
opened, select the third option above.

Note that only those windows that don't request a specific screen are
effected by the OPEN_WINDOWS settings; all windows that usually open on a
custom screen will still open there regardless of the setting of OPEN_WINDOWS.

The OPEN_WINDOWS submenu also includes a SIZE_TO_FIT option.  Since some
screens are not as large as the Workbench screen, some windows that usually
open on the Workbench screen might not be able to open on the active
screen.  For this reason, wIconify may resize a window in order to make it
fit on the screen.  When a window would not fit on the specified screen,
wIconify first looks to see if the window has a drag bar; if it does, then
wIconify tries to move the window so that it will fit on the screen.  If
not, or if the window is still too big, wIconify checks to see if the window
has a sizing gadget (or if it accepts NEWSIZE messages).  If so, wIconify
will change the size of the window to fit on the screen, and will send a
NEWSIZE message to the altered window.  If none of the above conditions
hold, wIconify will attempt to open the window unaltered.

Some badly-behaved programs, however, use the failure of an OpenWindow()
call to determine whether the Workbench screen is interlaced or not by
attempting to open a very tall window.  In this case, wIconify may "fix" the
window to fit, and the program will incorrectly believe that the screen is
interlaced when it may not be, and will overestimate the amount of space
available to it.  Under such circumstances, you may wish to turn off the
SIZE_TO_FIT menu.  If you do, wIconify will never attempt to alter the size
of a window when it is opening.  This may cause some windows to fail to
open, particularly on small screens.

You can customize the initial settings of the OPEN_WINDOWS submenu using the
wIconify initialization file (see CUSTOMIZING WICONIFY below).

One of the reasons that Intuition usually does not allow programs to share a
screen is that one program could close the screen while the other was still
using it, which would cause a system crash.  wIconify overcomes this problem
by keeping track of the windows that it has opened on other screens; a
screen will not be allowed to close until all "foreign" windows have been
closed first.  Thus it is completely safe to use wIconify to open windows on
other screens.


SCREENS CREATED BY WICONIFY:

Since wIconify allows you to turn any screen into a Workbench screen (as
described in SCREEN MANAGEMENT WITH WICONIFY above), it is convenient to
have a method of creating screens expressly for this purpose.  wIconify
provides this in the form of the NEW_SCREEN submenu of the SCREEN menu,
which lets you choose the depth and resolution of the screen to be created.

To create a new screen, choose the resolution options you want (HIRES, LORES,
INTERLACE, HAM), and then select the depth.  When you choose a depth item,
wIconify opens the new screen with the given specifications.  The resolution
items are updated to the values for the current screen whenever the active
screen changes, so it is most convenient to create a new screen from one
that is already of the resolution you want.

The actual width and height of the new screen are calculated from the width
and height of the current screen (doubling or halving as necessary to
accommodate the resolution requested).  The depth, of course, is up to you,
except for HAM mode screens, which always are 6 bitplanes deep (select any
depth for HAM screens; wIconify will substitute 6 automatically).

The colors for the new screen are the Intuition default colors, unless you
specify a new color map using the initialization file (see CUSTOMIZING
WICONIFY below).

Once the screen is created, it becomes the current WB screen automatically
(although the OPEN_WINDOWS option is not changed, so if ACTIVE_SCREEN is
selected the current WB will have no effect).  The new screen is activated
and ready to be used.  You can open as many wIconify screens as you have
memory for.  wIconify screens can be very useful for keeping your Workbench
less cluttered.

If you want to close a wIconify screen, use the CLOSE_SCREEN item of the
SCREEN menu.  It will be available only on wIconify-created screens, and
only when the screen has no windows or icons open on it.

All the menu items (except screen depths) have visible command-key equivalents.
The depths have command-key equivalents as well, but they are not visible.
The right-Amiga key together with a number from 1 to 5 (either on the keypad
or the main keyboard) is equivalent to selecting one of the depths in the
submenu.


NEWCLI'S CREATED BY WICONIFY:

Another useful feature of wIconify is its ability to create new CLI
processes at will.  The NEW_CLI item of the SCREEN menu causes wIconify to
attempt to start a new CLI process on the screen where the command was
given.  The default command used by wIconify is NEWSHELL, but you can
customize this in the initialization file (see CUSTOMIZING WICONIFY below).
In fact, you can give a separate command for HIRES screens and LORES
screens, in case you need to specify window sizes in the command.

When you select NEW_CLI, the active screen becomes the current WB screen,
but the setting of the OPEN_WINDOWS menu does not change.

wIconify uses the AmigaDOS Execute() routine to perform the NEW_CLI
command.  The Execute() routine requires that you have the RUN command
available in your C: directory (it does not look through the command path,
but looks in C: directly), so if you get a system requester for your startup
disk, that's probably why.

There are a number of important aspects of the newly created process that
you should be aware of when you use the NEW_CLI menu.  First, due to the way
the wIconify process is set up initially, the newly-created process does not
inherit a command path.  Second, despite the best efforts of the author, it
does not inherit a current directory, either.  The current directory turns
out to be NULL, which is supposed to mean the root of the initial startup
disk.  Unfortunately, this does not always seem to operate correctly.  It is
a wise precaution to perform a CD command even if you want to use the root of
the startup disk.  Third, the newly-created process's system-error screen is
by default the (real) Workbench screen.  Fourth, the command stack size of the
new precess is not inherited; you will have to set this yourself if necessary.
Finally, the newly-created process has input and output redirected to NIL:.

There are a number of methods you can use to overcome these problems.  For
the first two problems, you can explicitely state the path to the command
(or use an ASSIGNED path if you want to be able to change it).  For the
third problems, wIconify provides a separate utility program called
wSetSysRequest that set the screen for the system error messages to the
currently active screen.  You should create a file that contains the
wSetSysReqest command on one line then the command you want executed on the
next.  Finally, have NEW_CLI perform an EXECUTE command specifying the file
you just created as the file to perform.  You any also want to include a
PATH and CD command in the file.  For the fourth problem, you need to add
a STACK command to the file that you EXECUTE.  Finally, for that last
problem, simply include command redirection on the command you want to
perform so that it opens a CON: or NEWCON: window itself.

If you want the NEW_CLI menu to perform a NEWCLI or NEWSHELL command, there
is a particularly easy way to do this.  Create a file in your S: directory
called 'wIconify-CLI-Startup' that includes the CD, PATH, wSetSysRequest,
and STACK commands described above.  Then, use the initialization file to
specify the NEW_CLI command to be NEWCLI FROM S:WICONIFY-CLI-STARTUP or
NEWSHELL FROM S:WICONIFY-CLI-STARTUP according to your preference of CLIs.
This will cause the NEW_CLI command to open a new CLI that already has the
proper CD, PATH, etc. set up.  You may also want to include the command
EXECUTE S:CLI-STARTUP or EXECUTE S:SHELL-STARTUP if you want the new CLI to
perform the startup commands you usually use (see the AmigaDOS manual for
more information on the CLI, Shell, and startup files).


THE WICONIFY MENUS:

Every wIconify window has two main menus, the ICON menu and the SCREEN
menu.  These are described below:

The ICON menu includes the items that manipulate icons:

    OPEN        Opens all selected icons (restores their windows and
                removes the icons from the screen)

    CLOSE       Attempts to close the windows associated with the selected
                icons.  This option is only available to windows that have
                Intuition close gadgets.

    LOCK        Marks the selected icons as locked; that is, wIconify will
                not allow them to be moved by dragging, and they will be
                unaffected by the CLEANUP and ORGANIZE menus.

    UNLOCK      Unlocks the selected items; i.e., allows them to be moved again.

    CLEAN UP    Moves the selected icons to the closest "grid" positions.
                If no icons are selected, all (unlocked) icons are cleaned up.

    ORGANIZE    Moves all (unlocked) icons to the bottom of the screen.

    OPEN ALL    Opens all icons on the screen (without your having to select
                them all).

    ABOUT       Displays a short message detailing the program name, author
                and copyright notice.  This display appears in the screen's
                title bar area.

    END         Attempts to end wIconify.  This requires the RUN command in
                the C: directory, and access to the wIconify command in the
                WICONIFY: directory.  wIconify will not end until all
                "foreign" windows are removed from custom screens, all
                icons created by the programmer's interface are closed, and
                all wIconify screens are removed.  See ENDING WICONIFY below
                for more details.

The SCREEN menu contains commands to manipulate screens:

    TO FRONT        Brings the selected screen to the front.

    TO BACK         Sends the selected screen to the back.

    WB TO FRONT     Brings the current WB (as defined by the MAKE WB menu)
                    to the front.

    TOGGLE TITLE    Hides/shows the screen's title/menu bar.

    ICONIFY         Iconifies the selected screen; the screen will disappear
                    and be replaced by an icon on the Workbench screen.

    NEW CLI         Attempts to open a new CLI window on the current screen,
                    and makes the screen the current WB screen.  This requires
                    the RUN command in the C: directory.  The actual command
                    executed is set by the initialization file, and is the
                    NEWSHELL command by default.  See NEWCLI'S CREATED BY
                    WICONIFY above for more details.

    MAKE WB         Marks the selected screen as the current WB screen, and
                    selects the CURRENT WB item in the OPEN WINDOWS menu.
                    wIconify will open windows on this screen that would
                    normally be opened on the Workbench screen.

    OPEN WINDOWS    Specifies where and how windows will open that normally
                    would be directed to the Workbench screen.

        ACTIVE SCREEN   Windows open on the current active screen.

        CURRENT WB      Windows open on the screen marked as the current WB
                        screen by the MAKE WB menu.

        REAL WB         Windows open on the (real) Workbench screen as usual.

        SIZE TO FIT     Windows that are too big for the screen where they
                        will open will be resized to fit on the screen.

    NEW SCREEN      Allows you to open new screens for use as WB screens.

        1  2  3  4  5   Specifies the depth of the screen to open.  The
                        screen is opened as soon as the depth is selected.
                        The command-key equivalents are right-Amiga plus the
                        depth (either on the keypad or main keyboard).

        HIRES           Sets the horizontal resolution to HIRES (usually
                        640 pixels across).

        LORES           Sets the horizontal resolution to LORES (usually
                        320 pixels across).

        INTERLACE       Sets the vertical resolution to Interlaced
                        (usually 400 pixels down) or Non-Interlaced
                        (usually 200 pixels down).

        HAM             Set the special HAM (Hold-And-Modify) mode.  This is
                        not available in HIRES INTERLACE mode, but in all
                        others.  Any depth will be converted to 6 bit planes
                        automatically.

    CLOSE SCREEN    Attempts to close a wIconify-created screen.  This is only
                    allowed when all the windows and icons are removed from
                    the screen.

The menu command-key equivalents can be customized via the initialization
file; see CUSTOMIZING WICONIFY below.


CUSTOMIZING WICONIFY:

Many parts of wIconify can be customized, including the icon imagery, the
button or key-stroke that iconifies a window, the menu command-key
equivalents, and many other features.  To change any of the defaults, you
must supply a wIconify initialization file, which you can specify on the
command line when you start wIconify.  For example:

    1> wIconify wIconify.init

If you do not specify a file, wIconify will look for WICONIFY:wIconify.init
and if it is not found, it will look for S:wIconify.init.  If neither is
found, it will use the default values for everything.

The wIconify.init file is a text file that you can create or edit using any
text editor, such as ED, EDIT, or Emacs.  A sample initialization file,
Sample.init, is provided as part of this distribution.

The initialization file should contain a series of commands that specify
what defaults you want to change.  Each command keyword must be followed
by a colon (':'), and you should have only one command per line.  Some
commands can take up more than one line.  Blank lines are ignored, in
general, although a blank line will end a multi-line command.

You can include comments in your initialization file in two ways.  First,
the semi-colon (';') is a comment character, which means that everything on
the line past the semi-colon will be ignored.  This is the same as for the
CLI.  The Sample.Init file has numerous examples of the use of the semi-colon
as a comment.

The second type of comment is not line-oriented; instead, it is delimited
by a comment initiator and a comment terminator.  These are '/*' and '*/',
respectively.  They are the same as the comment characters in the C
programming language.  You can nest comments within comments, as in the
following example:

    /* This is a comment /* inside */ another comment */

Be careful that you pair these together properly, or you may find that your
whole initialization file becomes a comment!


The commands allowed within the initialization file are the following:


Format:

    ICONIFY_KEY: qualifiers keyname

This specifies the key or button press that causes windows to become
iconified.  The default is the left-right click.  Qualifiers can be separated
by spaces, pluses (+), or bars (|), and the keyname should be separated from
the qualifiers by a space.  If a qualifier name is preceded by a dash (-) this
specifies a "disqualifier", that is, the specified qualifier must NOT be
pressed when the key is pressed; such qualifiers prevent the key-press from
iconifying windows.

The qualifiers must be chosen from the following list:

    LSHIFT          The left SHIFT key
    RSHIFT          The right SHIFT key
    CAPSLOCK        The Caps Lock key
    CONTROL         The CTRL key
    LALT            The left Alt key
    RALT            The right Alt key
    LCOMMAND        The left Amiga key
    RCOMMAND        The right Amiga key
    LAMIGA          The left Amiga key (same as LCOMMAND)
    RAMIGA          The right Amiga key (same as RCOMMAND)
    NUMERICPAD      The key is on the numeric keypad
    LBUTTON         The left mouse button
    RBUTTON         The right mouse button
    MBUTTON         The middle mouse button (future expansion)

The keyname must be one of the following:

    LBUTTONPRESS    The left button
    RBUTTONPRESS    The right button
    F1              The F1 key
    ...
    F10             The F10 key
    ESC             The ESCape key
    ENTER           The ENTER key on the keypad
    RETURN          The RETURN key
    BACKSPACE       The Back Space key
    DELETE          The DEL key
    HELP            The HELP key
    TAB             The TAB key
    SPACE           The space bar
    \nn             The key with keycode 'nn' where 'nn' is a HEX value;
                    for example, \4C is the up-arrow key.
                    (see the ROM Kernel Manual for a list of keycodes)

Examples:

    ICONIFY_KEY:  LBUTTON RBUTTONPRESS      ; this is the default
    ICONIFY_KEY:  LSHIFT F2                 ; F2 with LSHIFT held down
    ICONIFY_KEY:  LSHIFT-RSHIFT ENTER       ; ENTER with LSHIFT but not RSHIFT
    ICONIFY_KEY:  LSHIFT+RSHIFT ENTER       ; ENTER with LSHIFT and RSHIFT
    ICONIFY_KEY:  F6                        ; F6 with no special qualifiers


Format:

    CHANGE_REFRESH:  qualifiers

This specifies the qualifier keys that cause SMART_REFRESH windows to be
converted to SIMPLE_REFRESH windows when they are iconified.  The default is
LALT.  If the qualifiers specified are held down when the Iconify-Key is
pressed, then the window's refresh type will be changed, otherwise it will
remain unchanged when it is iconified.  The qualifiers must be chosen from
the list given above, and can be separated by a space, a plus (+) or a bar (|).
Disqualifiers are not allowed in the CHANGE_REFRESH specification.

Examples:

    CHANGE_REFRESH:  LALT                   ; the default
    CHANGE_REFRESH:  CONTROL+LSHIFT


Format:

    ACTIVATION_KEY:  qualifiers keyname

The specifies the key or button press that activates the wIconify backdrop
window on the active screen.  By default it is LSHIFT F1.  The qualifiers,
disqualifiers, and keyname are specified as in ICONIFY_KEY above.

Examples:

    ACTIVATION_KEY:  LSHIFT F1          ; the default
    ACTIVATION_KEY:  LSHIFT-LALT F1     ; LSHIFT F1 when LALT is not pressed


Format:

    COLOR_MAP:
       rgb
       ...

This command specifies a color map to be used for all wIconify screens
created by the NEWSCREEN menu (or wIconScreen command).  The lines following
the COLOR_MAP command specify RGB gun intensities for each color, color 0
being the first line, color 1 being the second, etc.  The RGB values are
specified as HEX digits (0-F) representing 0 to 15.  For example, F00 is
bright red, FF0 is yellow, 888 is grey, etc.  You can use the Palette or
Preferences tools provided with the Workbench to experiment with different
color values.

There are also two special color values.  If the first character in the color
specification is an equal sign (=) or an asterisk (*), this means that the
color should be the default color used by Intuition (the first four colors
are set by the Preferences tool, and the others are the default ugly colors).

Example:

    *       ; use the default WB background color
    *       ; and the default forground color
    888     ; but use grey for color 2
    FFF     ; and white for color 3
            ; additional colors could go here for screens with more bitplanes.


Format:

    MENU_KEYS:
      menuname  letter
      menuname  letter
      ...

This command specifies the menu command-key equivalences.  Here, menuname
represents the name of one of the menus (e.g., OPEN, CLEAN_UP, ACTIVE_SCREEN),
and the letter following it is the key to be used as the command-key
equivalent; it must be a printable character.  If no letter follows the
manu name, then this menu will not have a command-key equivalent.  It is not
possible to change the command-key equivalents of the depth items in the
NEW_SCREEN menu, but all other items can be modified.  Note that spaces in
menu names are replaced by underscores.  For submenus, just the name of the
submenu itself is used as the name.

Example:

    MENU_KEYS:
      OPEN          O
      CLOSE         C
      LOCK          #
      CLEAN_UP      K
      ORGANIZE      R
      OPEN_ALL      P
      ABOUT         ?
      END

      ACTIVE_SCREEN A
      CURRENT_WB    W
      REAL_WB       =
      SIZE_TO_FIT   S


Format:

    DEFAULT_FLAGS:  flags

This specifies the icon flags that will be set automatically for all window
icons created by wIconify.  If no flags are provided, then no special flags
are applied when a new icon is formed.  The flags can be separated by spaces,
plus signs (+), or vertical bars (|), and must come from the following list:

    CHANGEREFRESH   SMART_REFRESH windows will become SIMPLE_REFRESH when
                    they are iconified
    LOCKED          The icons will be locked
    NOMOVE          The icons will not be allowed to be dragged
    NOCLOSE         The CLOSE menu will be unavailable for these icons
    NOORGANIZE      The ORGANIZE menu will not affect these icons
    NOSAVEPOS       The window's icon will go to the bottom of the screen
                    every time it is iconified
    NOMULTISELECT   The icons can only be selected one at a time
    NOICONIFY       The windows will not be able to be iconified again

These flags are part of the programmer's interface, and most of them do not
make sense to use as the default window icon flags, except perhaps
CHANGREREFRESH and perhaps NOSAVEPOS.  They are provided for completeness.

Examples:

    DEFAULT_FLAGS:                  ; default is no special flags
    DEFAULT_FLAGS:  CHANGEREFRESH   ; change SMART to SIMPLE refresh
    DEFAULT_FLAGS:  CHANGEREFRESH | NOSAVEPOS


Format:

    SCREEN_FLAGS:  flags

This specifies the icon flags to be given to screen icons when they are
created.  The flags are specified as for DEFAULT_FLAGS above, and must be
chosen from the same list of options.  The CHANGEREFRESH flag has no effect
for screen icons, however.  Screens automatically get the NOCLOSE flag.


Format:

    IGNORE_SCREEN:
        screen1
        screen2
        ...

This command specifies the names of screens that should be ignored by
wIconify.  wIconify will not open a backdrop window on these screens,
windows on these screens will not be able to be iconified, nor will wIconify
route Workbench windows to these screens.  These screens are completely
ignored by wIconify.

The name of a screen need not be its complete name; you only need to
specify enough of the name to distinguish it from other screens.  Upper and
lower case letters are not distinguished, but spacing is important.  If the
screen name has leading or trailing spaces, you will need to enclose it in
single quotation marks (').  If you need a single quote within the the
single quotes, use two single quotes in a row ('').  A screen with no title
is specified by empty quotes ('').

If you do not use quotes around the name, the entire line (minus any leading
and trailing blanks) is used as the name.

Examples:

    IGNORE_SCREEN:
        '  A screen with leading blanks'
        ''      ; no title
        A full-line title


Format:

    HIRES_CLICOMMAND:  command-string
    LORES_CLICOMMAND:  command-string

These commands specify the commands performed by the NEWCLI menu item.  The
command string can be enclosed in quotation marks (as described in
IGNORE_SCREEN above), or can be the rest of the line.  See NEWCLI'S CREATED
BY WICONIFY for information about the current directory, etc., used by this
command.  The LORES command is used whenever the NEWCLI menu is selected
on a LORES screen, and the HIRES command is used otherwise.  If no LORES
command is given, then the HIRES command will be used instead.  The default
commands are 'NEWSHELL' for the HIRES command, and nothing for the LORES
command.

Examples:

    HIRES_CLICOMMAND:   NEWSHELL        ; the default
    HIRES_CLICOMMAND:   NEWSHELL FROM S:WICONIFY-SCRIPT
    HIRES_CLICOMMAND:   'EXECUTE WICONIFY:NEWCLI-COMMAND'
    HIRES_CLICOMMAND:   NEWSHELL NEWCON:0/10/640/100/AmigaShell
    LORES_CLICOMMAND:   NEWSHELL NEWCON:0/10/320/100/AmigaShell


Format:

    COMMAND_STACK:  stack-size

When you select the NEWCLI menu, a separate process is created to perform
the CLI command that you want executed (usually this is NEWSHELL, but you
can specify another command using the HIRES_CLICOMMAND or LORES_CLICOMMAND
commands described above).  In the default case, this process simply
performs the NEWSHELL command (creating the new shell), then exits, but if
you change the command to something else, you may want a larger stack than
the default 4K.  The COMMAND_STACK command lets you specify the stack size.

Examples:

    COMMAND_STACK:  2048        ; a 2K stack
    COMMAND_STACK:  10240       ; a 10K stack (a good size)


Format:

    OPEN_ON:    screen-type

This command specifies the setting of the OPEN WINDOW submenu.  The valid
screen-types are:  ACTIVE_SCREEN, CURRENT_WB, and REAL_WB.  These specify
where windows will open that usually would open on the Workbench screen.
ACTIVE_SCREEN specifies that they will open on the currently active screen,
CURRENT_WB indicates that they should open on the screen you selected with
the MAKE_WB menu item, and REAL_WB means they should open on the Real
Workbench screen (i.e., wIconify should not change where windows open).
The default is to open windows on the active screen.

Example:

    OPEN_ON:    ACTIVE_SCREEN   ;   The default


Format:

    SIZE_TO_FIT:    TRUE-or-FALSE

This command sets the SIZE_TO_FIT item of the OPEN_WINDOWS submenu.  If you
specify TRUE, wIconify will resize windows, if necessary, in order to allow
them to open on screens other than the Workbench.  If you specify FALSE,
wIconify will not adjust the window sizes (some attempts to open windows on
small screens may fail).  The default setting is TRUE.

Examples:

    SIZE_TO_FIT:    TRUE    ; the default
    SIZE_TO_FIT:    FALSE   ; the only other choice


Format:

    DEFAULT_IMAGE:
       bitmap-data
       bitmap-data
       ...

This command allows you to specify the image to be used by new icons (that
don't specify their own images).  Each of the lines that follow the
DEFAULT_IMAGE command becomes a row of the image.  Each character on the line
(past the opening blanks) represents the pen color of one pixel of the row.
For a 2 bit-plane screen, the colors range from '0' to '3'; for 3 bit-planes
they are from '0' to '7';  For 4 bit-planes, they are '0' to '9' and 'a' to
'f' (these must be lower case letters); for 5 bit-planes, they are 0-9
and a-f for the first sixteen pen colors, and then SHIFT 0-9 and SHIFT A-F
for pens from 16 to 31.  That is, ')' is pen 16, '!' is pen 17, '@' is pen 18,
'#' is pen 19, up through '*' as pen 24 and '(' as pen 25.  Then 'A' is pen 26,
up through 'F' as pen 31.  This allows you to specify a 5-bitplane image if
you want.

Be careful that your images make sense in fewer bitplanes, though.  You want
to use a mix of even and odd numbers so that something will show up on one
bit-plane screens.

The standard size, is 41 by 18, though you can specify larger or smaller
icons if you want.  The maximum size is 78 by 32 (the size of the icon grid
spacing).  wIconify will warn you if your image exceeds this amount.

See the Sample.Init file for a complete example of how to specify an image.


Format:

    DEFAULT_SELECT:
        bitmap-data
        bitmap-data
        ...

This command specifies the image to be used when the icon becomes selected.
If no DEFAULT_SELECT command is given, then the select image will be an
inverted copy of the default image.  If a select image IS given, it should
be the same width and height as the default image.  The bitmap-data has the
same form as the DEFAULT_IMAGE above.

See the Sample.Init file for a complete example of specifying a select image.


Format:

    DEFAULT_MASK:
        mask-data
        mask-data
        ....

This command specifies the image mask to be used with the default icon.  The
mask data has the same format as the image bitmap-data described above,
except that only pen values of 0 and 1 are allowed.  A 0 represents places
where you can "see through" the icon when it is being dragged.

If a select image was given, the mask is associated with the selected image,
otherwise, the mask is associated with the image itself as well as with its
inverted select image.  The mask data must be the same size as the other two
images.

In addition to determining what part of the image is invisible, the mask also
is used as a "hit mask"; that is, when selecting an icon with a mask, you must
click on one of the pixels that is a 1 in the mask data.  If a select image
was specified, the mask will be used as a hit mask only when the select image
is showing, otherwise it will be used all the time.  The example in the
Sample.Init file has a mask with fairly large "holes" in it that you can
experiment with.


Format:

    DEFAULT_ICON:  filename

It is sometimes more convenient to have the bitmap data for the default icon
stored in a separate file (for example, a file created by one of the
wIconSetter icon-creation utilities).  In this case, you can use the
DEFAULT_ICON command to specify the file that contains the icon imagery.
This file can contain three commands: ICON, SELECT, and MASK.  These have
the same format as DEFAULT_IMAGE, DEFAULT_SELECT, and DEFAULT_MASK above.
No other commands are allowed in the icon file itself.

Example:

    DEFAULT_ICON:  WICONIFY:Window.Icon


Format:

    SCREEN_IMAGE:
    SCREEN_SELECT:
    SCREEN_MASK:
    SCREEN_ICON:

These commands have the same format as the corresponding DEFAULT commands
described above, however, these ones determine the default imagery for the
screen icons, whereas the previous ones are for the default window icons.


Format:

    PRIORITY:   n

This specifies the priority for the wIconify handler process (the process
that maintains the icons and wIconify backdrop windows).  The default
priority is 0, but you may want to bump this up to 5 or so.  The trackdisk
device runs at priority 5, the DFn: file-system tasks run at priority 10,
and the Input.Device runs at priority 20.  You must specify a priority in
the range -128 to 127, though it probably is unwise to go above 10 or
below 0.

Examples:

    PRIORITY:   0       ; the default
    PRIORITY:   5       ; wIconify runs before the CLI's


Format:

    HANDLER_PRIORITY:  n

This command specifies the priority in the Input.Device input handler chain
of wIconify's input handler.  The default is 51, which puts it just in front
of Intuition (which is at priority 50).  Many utilitiy programs install
their own input handlers, and it may be necessary to use the priorities to
adjust the sequence in which these get to see the input events.  Too many
programers have used priority 51 (inlcuding the author), and have hard-coded
the priority into their programs.  It is time that this begins to change.

Examples:

    HANDLER_PRIORITY:   51      ; the default
    HANDLER_PRIORITY:   53      ; a little bit earlier in the input chain


HOW WICONIFY WORKS:

wIconify is made up of five distinct parts:  an Input.Device input handler,
the traps to the Intuition routines, an AmigaDOS process, the loader, and the
programmer's interface.  Each of these operates within different process
contexts, which makes for extremely delicate and complex interaction among
these components.

The Input.Device handler is the smallest piece.  Its job is to search the
input chain for left-right mouse clicks (or whatever key is specified as the
iconify key), remove them and inform the handler process about them.  In the
same way, it looks for the wIconify activation key (SHIFT F1) and activates
the wIconify backdrop window when found.  Finally, the handler also checks
to make sure that iconified windows and screens do not become activated
accidentally (input events should only go to non-iconified windows).

wIconify traps a number of Intuition routines, namely OpenWindow(),
CloseWindow(), OpenScreen() and CloseScreen().  The OpenWindow() trap checks
to see if the window should be opened on a different screen, and if so,
check whether it needs to be resized before it attempts to open the window.
It also maintains the data required to tell when all the "foreign" windows
have been removed from a screen.  Finally, it looks for the Workbench window
opened by LoadWB and modifies it to include standard border gadgets, etc.
The CloseWindow() trap checks to see if the window has an icon, and if so
requests the handler process to remove the icon.  If the window is on a
"foreign" screen, it updates the data needed to determine when it is safe to
close a shared screen, and if the screen is waiting to close, it may signal
that it is OK to be closed.

The OpenScreen() trap checks if the newly-created screen is one that it is
supposed to ignore, and if not, it tries to open the wIconify backdrop
window on the screen.  The CloseScreen() trap first attempts to remove any
icons that it can from the screen, then it waits for any "foreign" windows
to be closed and any icons to be removed by the user.  Finally, it closes
the wIconify backdrop window and closes the screen.

wIconify also traps a number of other routines, specifically,
WindowToFront(), WindowToBack(), and ActivateWindow().  These traps check
that the window being specified is not and iconified window.  This prevents
iconified window from reappearing or becoming activated accidentally.
Finally, wIconify traps the wSetWindowTitles() routine in order to update
the name of an icon if its window title changes.

Finally, wIconify traps AutoRequest(), BuildSysRequest() and FreeSysRequest().
These routines open (or close) windows, but since they are part of the
Intuition library itself, and since Intuition does not call its own vector
table, these rooutines bypass the traps that wIconify has installed in
OpenWindow() and CloseWindow().  In order to properly handle the windows
created for System Requests, wIconify also must trap these routines.  In
BuildSysRequest(), the windows are handled almost exactly as normal windows
are, except that if the calling task is a Process and that process has an
error window defined (by wSetSysRequest, for example), then the window will
be opened on the screen containing that window regardless of the settings in
the OPEN_ON menu.

Window opened by BuildSysRequest() are new fully supported by wIconify:
they can be iconified and manipulated as usual, their icons will be removed
when they close, and their presence on a "foreign" screen will prevent that
screen from closing before the system request is completed.

The AutoRequest() routine presents more of a challange, since it does not
return control until after the system request window has been completed.
Thus wIconify never gets the chance to manipulate the window it creates,
either to move it to another screen, or to maintain the internal data
required for an icon.  For this reason, the AutoRequest() routine has been
completely replaced by an equivalent routine.  This routine calls (the
modified) BuildSysRequest(), and then waits for the user to complete the
request.  The action of the AutoRequest() routine is well-documented in the
Intuition manual, so this replacement should be indistinguishable from the
original under normal circumstances.

All these traps run in the context of the process or task that calls the
trapped routine, not in the context of the wIconify handler process, so
they do not manipulate the linked lists of icons directly.  Rather, they
communicate with the wIconify handler process via Exec messages.

The main handler process is the central component of wIconify, and it has a
number of jobs.  First, it is in charge of maintaining the linked lists
of icons, screens, windows, etc. that are used by wIconify.  Since the
different parts of wIconify all run asynchronously under different process
contexts, the lists could get seriously tangled if more than one process
were trying to modify them at once.  For this reason, the handler process is
the only one that adjusts the icon lists (although the screen and window
lists are maintained by the trap routines).  The handler responds to
requests from the Input.Device handler and the Intuition Trap routines to
add or remove icons.  This includes the actual "removal" and restoration of
windows and screens as they are iconified.

The second job of the handler is to manage the wIconify backdrop windows and
the Intuition events associated with them.  This involves the actual drawing
of the icons as well as processing the mouse clicks and moves that cause
icons to be selected, dragged, and opened.  It also includes responding to
all menu selections, and updating the menu items as needed.  This includes
opening and closing new screens, and starting NewCLI processes.

Finally, the handler also responds to requests from other programs that use
the wIconify programmer's interface to manage their own icons.  This
includes adding, removing, and selecting icons, iconifying and restoring
windows and screens, and looking up information about icons.  See the
wIconify programmer's interface documentation for more information.

The loader is the portion of wIconify that is actually named "wIconify"
(the Input.Device handler, Intuition traps, and handler process all are
encapsulated in the "wIconify-Handler").  Its job is to load the handler
code into memory and set up the data needed by the different components of
the handler, install the traps and Input.Device handler, and start the
handler process itself.  A major portion of this job is to read and process
the intialization file and report any errors with it.  If the loader detects
that the handler already is loaded, then the loader signals the handler that
it should attempt to quit running.  When the handler responds that it is
done, the loader will remove the traps and input handler, and then remove
the handler process from memory.

Although the handler is over 30K in size, it has been streamlined as much as
possible.  In particular, any non-essential functions have been moved to the
loader.  Thus all the initialization and run-down code is in the loader not
the handler.  In fact, the handler process can not end on its own; it
requires the loader to help it out.  When you choose the END item in the
ICON menu, the handler process attempts to Execute() the wIconify command
as a separate process just as though you typed wIconify again yourself.
See ENDING WICONIFY for more details.

In order to iconify windows, wIconify turns them into BACKDROP windows and
then sends them to the back.  They fall behind the wIconify backdrop window
where they can no longer be seen, which makes them seem to disappear.  This
has some serious implications concerning memory usage; see WICONIFY AND
SMART_REFRESH WINDOWS above for more details.

To iconify screens, wIconify simply moves them below the visible area of the
display; thus they seem to disappear.  The legality of this is not strictly
clear.  It is not prohibited by the Intuition guide, but it may cause
unforeseen problems.

Note that in both cases, the screens and windows are not actually removed.
They still exist and are usable by the programs that created them.  Every
effort was made to prevent iconified windows from becoming activated or
depth-arranged accidentally, but the fact that they exist when they appear
not to may cause some problems with some programs, such as hot-key programs
that allow you to depth-arrange windows or screens.  For example, these
programs may not cycle the screens correctly.  wIconify attempts to push
iconified screens to the back whenever possible, so if your hot-key program
pulls it to the front, wIconify will immediately push it to the back again.


ENDING ICONIFY:

As you can see from the description above, wIconify is a complex system,
with a variety of connections into the system software and application
programs.  Shutting down and removing such a system is far from easy.
Nevertheless, the author feals that you should be able to remove any peice
of optional software without having to reboot the machine (apparently the
authors of the Workbench don't agree), so he has provided the END menu item
for this purpose.

Simply selecting END may not end wIconify, however.  A number of conditions
must be met in order to ensure that wIconify can end safely.  First, the END
menu item uses the Execute() AmigaDOS routine, which requires the RUN
command to be in the C: directory (it looks directly into the C: directory,
bypassing the command path altogether), and it requires that WICONIFY: be
assigned to the directory where the wIconify program is stored (usually C:
or the wIconify directory).  Second, all icons must be removed from all
screens (wIconify will open window icons and remove AUTOREMOVE icons
automatically when you ask it to END, but icons created by other programs
may require you to closed them individually before END will operate).
Third, all "foreign" windows must be removed from shared screens (you must
close these manually).  Fourth, all wIconify-created screens must be closed
(wIconify automatically will close any screens that have no windows, but you
will have to close any windows on wIconify screens before they will be
closed).  Fifth, wIconify will not end while there are un-replied messages
associated with the wIconify programmer's interface, or with closing or
resized windows.  Finally, if the Intuition routines trapped by wIconify
have been re-trapped by some other program, wIconify may not be able to
restore its own traps, hence will not end.

The last two of these are particularly hard to detect.  In both cases, it
will appear that wIconify has ended (there will be no more visible signs of
its operation), but the process will still be running and the memory in use
by it will not be freed.  Furthermore, there is virtually nothing you can do
about un-replied messages; if a program fails to reply to a message, there is
no way for you to get around this, but it would be unsafe for wIconify to
end without waiting for all its messages to be returned.

The problem with the traps is a design flaw with the SetFunction() mechanism:
the programs that use SetFunction() must be removed in the opposite order from
which they were started.  Fortunately, there is a solution.  The author of
wIconify also wrote a program called PatchSetFunction which makes it possible
to add and remove traps in any order.  He strongly recommends that you use
this program, especially if you have lots of system-modifying programs like
wIconify.  The program can be obtained from the author.

The other conditions can be met simply by closing windows or icons, and by
providing the proper directory name assignments.

This all probably seems pretty complicated just to end a program, but the
author wishes to be as safe as possible.  Despite this effort, however,
there are still possible places where problems can occur.  In general, if
you are not using any programs that use the programmer's interface, you are
probably safe in ending wIconify at any time.  If you use programs that
supply their own icons (particulary icons with no windows attached), it is
best if you end these programs first before attempting to end wIconify.

If wIconify fails to end (one of the above conditions is not met), then
wIconify may be left in "limbo".  When wIconify is trying to end, it will
not allow new windows to become iconified, and may not open new screens, etc.
This is a particularly delicate time for wIconify (many unforeseen
conditions can occur internally during this phase), so you should try to
minimize it, when possible, by closing windows, screens and icons BEFORE
requesting wIconify to end.

Once all the conditions are met, wIconify will end on its own (there is no
need to request it to end again).

If you used the wIconify command to end iconify (rather than the END menu)
the wIconify command will not complete until the handler has ended.  If you
feel that the handler will not be able to end, you can cancel wIconify by
pressing CTRL-C.  DO THIS ONLY AS A LAST RESORT, however, since if the handler
is able to end, there will be no loader ready to clean up after it!
At this point, issuing another wIconify command will cause the handler to go
through its shut-down process again, although if it didn't succeed the first
time, it probably won't do so now.

When you use the END menu item to end wIconify, the handler actually
executes the loader as a separate process via the Execute() routine.  If
wIconify fails to end properly (for one of the reasons above), this process
will still be waiting for it to end.  Selecting END again will cause
additional processes to be started.  You can use the STATUS command to see
if any of these are still active, and if so, you can use the BREAK command
to send a CTRL-C to those processes if you want to remove them.  See the
AmigaDOS manual for information on the STATUS and BREAK commands.


WICONIFY AND THE STARTUP SEQUENCE:

wIconify usually should be part of your startup sequence, and its position
within the startup-sequence file is important.  If you are using
wIconSetter, you should put the wIconify command early in the sequence
(before too many windows are open) and the wIconSetter command immediately
after it.  If you want wIconify to work properly with the Workbench window
(see HOW WICONIFY WORKS above), you should put the LoadWB command after the
wIconify command.

A number of other programs also have interactions with wIconify that may be
dependent on the order in which they are installed relative to wIconify.
See INTERACTIONS WITH OTHER PROGRAMS below for more details.

Once wIconify is installed, there are a number of utilitiy programs that may
be useful in your startup sequence.  For example, you may want to have a new
wIconify screen opened as your Amiga boots up, and use this screen as an
additional Workbench screen on which you open utility programs that you use
often, or you may want to start some programs and have their windows be
iconified during the boot process.

Both these functions can be performed by the wIconify utility programs.
These include:

    wIconScreen         Opens a new wIconify screen

    wIconifyWindow      Iconifies a window (and allows you to specify
                        the icon's position and icon flags)

    wIconifyScreen      Iconifies a screen (and allows you to specify
                        the icon's position and icon flags)

    wMakeWB             Selects a screen as the current WB screen

    wOpenOn             Sets the OPEN WINDOWS submenu selections

    ScreenToFront       Depth arrange screens
    ScreenToBack

Each of these is documented sepearately; see these documents for complete
details on how to use these programs.

If you plan to open extra Workbench screens where you will open many
utilitiy programs during boot-up, you may want to consider changing the
default OPEN_WINDOW setting to CURRENT_WB; then, create the screen using the
wIconScreen command (the screen will not be activated, but will be the
current WB screen, so new windows will open there); then open the utilities
you want; finally, use wOpenOn to change the OPEN_WINDOWS menu back to
ACTIVE_SCREEN.  For example:

    wOpenOn CURRENT_WB
    wIconScreen HIRES NOACTIVATE BEHIND
    ; commands that open windows here
    wOpenOn ACTIVE_SCREEN

Once windows are open, you can use wIconifyWindow to iconify them during the
startup sequence, so your work area can be nice and clean as soon as your
machine boots up.  (You can also use the AUTOICONIFY flag within wIconSetter
to cause windows to iconify as soon as they open, but this will stay in
effect even after boot-up, so windows may iconify themselves when you hadn't
intended them to).


INTERACTION WITH OTHER PROGRAMS:

  LoadWB

    The Workbench opens a backdrop window to hold its disk and file icons.
    Since this window is the full size of the screen, it covers up the
    wIconify backdrop window making it hard to get to the window icons.
    For this reason, wIconify modifies the Workbench window when it opens
    so that it is a standard non-backdrop window with drag bar, depth gadgets
    and sizing gadget.  In order for this to happen, however, you must install
    wIconify BEFORE you start the Workbench with LoadWB.  See HOW WICONIFY
    WORKS above for more information.

  DropCloth

    DropCloth allows you to add a background picture or shading pattern to
    your Workbench window.  DropCloth is not very picky about the window
    it modifies, however.  In particular, it seems to take the back-most
    backdrop window.  If wIconify is running, this will be the wIconify window
    (this is probably what you want since the Workbench window is no longer a
    backdrop window).  On the other hand, if you have iconified windows, they
    will be turned into backdrop windows that are behind the wIconify
    backdrop, so in this case, DropCloth will add its picture or shading to
    the last iconified window (if any).  Thus you can have DropCloth do its
    magic to ANY window simply by iconifying it just before running DropCloth.
    If you want to remove DropCloth from such a window, be sure to iconify it
    again first.

  Less

    Less is a program like More, with additional features.  It does not
    behave very well, however (it does not respond to sizing its window,
    for example).  This program attempts to open a large window to see if
    the screen is interlaced, and if the OpenWindow() call fails, it
    opens a smaller window for non-interlaced screens.  If you have set
    the SIZE TO FIT option in the OPEN WINDOW submenu, however, wIconify
    will modify the initial window size to fit the screen, and Less will
    think the screen is interlaced.  It will miscalculate the size of the
    window and hence the number of lines that can fit in the window.
    For programs like this, you should disable the SIZE TO FIT option.

  QMouse

    QMouse is a small utilitity that incorporates a mouse accellerator, a
    menu clock, click-to-front, and a hole lot of other useful features, all
    in one small package.  Unfortunately, it seems that, in order to make
    it as small as possible, QMouse does not always do everything "legally".
    In particular, it does not seem to allocate the timer device correctly
    (it does not even contain the name of the timer device in its executable).
    For this reason, if you use QMouse, wIconClock will not be able to get
    access to the timer (in fact, its attempt to allocate the timer never
    seems to complete).  If you install wIconClock BEFORE you start QMouse,
    however, everything seems to work OK.  It may not be completely
    bugless, however.

  Screen and window hot-key programs

    These are programs that allow you to depth-arrange screens and windows
    via hot-keys.  Since wIconify does not actually remove windows when they
    are iconified (it only hides them), such programs may try to depth-arrange
    iconified windows.  wIconify tries very hard to prevent this, but the
    result is that your hot-key program may not do exactly what you think it
    should, due to the presence of unexpected backdrop windows.

    Similary, screens are not removed, just hidden, and their presence may
    confuse hot-key screen flippers as well.  wIconify is designed to favor
    programs that allow you to move the front screen to the back, but will
    probably disrupt programs that allow you to bring the back screen forward:
    wIconify pushes iconified screens to the back, so if they are moved to the
    front, wIconify will just send them to the back again.  You will never
    even see the screen come forward (since it is iconified), and the result
    will be that your screen-flipper appears to do nothing at all.

  Programs that write directly to the screen's RastPort

    The intuition guide suggests that programs always use a backdrop window
    for graphics rendering rather than go directly to the screen's RastPort.
    Unfortunately, some programs break this rule.  You may wish to have
    wIconify not open its backdrop window on such screens.  To do so, use
    the initialization file and the IGNORE_SCREEN command to specify the
    screens to be ignored.

  Programs that use Sprites:

    Some programs use the hardware sprites, which always appear above anything
    else on the screen (the mouse pointer is a sprite).  When these windows
    are iconified, the sprites will still appear in front of everything,
    which may be a bit confusing if they are supposed to look like part of
    the window.

    Also, if you open new "foreign" windows on a screen that is using
    sprites, the sprites may appear on top of the new windows.  This may
    be confusing if they are supposed to look like part of another window.


WHEN WICONIFY CAN FAIL:

In addition to the interactions described in the section above, there are
some additional situations that can cause confusing results:


A Window's Icon Appears but the Window Does Not Disappear:

This can happen when you are attempting to iconify a SMART_REFRESH window
when there is very little CHIP memory left.  Low memory conditions are very
touchy, and you should try to free up some memory right away, chances are
the system is about to crash due to a lack of memory.  If it survives, you
should open the window's icon (even though the window is still visible).
This is because wIconify has modified the window and attempted to send it to
the back, but Intution did not have enough memory to save the window's
contents off-screen.  There is no way for wIconify to know this, however,
since WindowToBack() does not return a success status.  Once you have freed
up some memory, try iconifying the window again.


A Window's Icon Disappers but the Window Does Not Reappear:

As with the problem above, this can be caused by very low CHIP memory
conditions.  What has happened in this case is that wIconify has attempted
to bring the window to the front, but there is not enough memory for
Intuition to save the parts of the windows that will become obscured.
wIconify has no way to determine this, however, so it removes the window's
icon, thinking that the window has appeared.  At this point, the window is
inaccessible as it is still behind the wIcoinfy backdrop window.  There is a
utility program called wIconVerify that will find any "lost windows" of this
type.  See the documentation for wIconVerify for more details.


Selecting the END Menu Item Doesn't Seem to End wIconify:

Ending wIconify is a more complex operation than you might at first think
(see ENDING WICONIFY above for complete details).  There are a number of
reasons wIconify can fail to end when you ask it to:

    The RUN command may not be in the C: directory, or the C: directory
    is on an unmounted disk (AmigaDOS goes directly to C:, bypassing the
    path, so wIconify must have access to C: in order for END to work).

    The WICONIFY: directory has not been assigned via the ASSIGN command
    (see INSTALLING AND REMOVING WICONIFY above for details).

    There are screens with non-window icons on them that can not be
    removed automatically (this can only be true if you are using programs
    that take advantage of wIconify's programmer's interface).

    There are windows open on shared screens other than the workbench.

    There are wIconify screens open with windows on them.

    There are un-replied messages held by programs using the programmer's
    interface, or due to attempts to close windows associated with icons.


Can't Create a NewCLI:

In order to create a new CLI, wIconify must have access to the RUN command
in the C: directory (being in the command path is not good enough).  It
must also have access to the NEWSHELL command, or whatever command you
specified in the initialization file.  The NewCLI also may fail if the
syntax of the command you specified is incorrect, the command can't be
found, or if the files required by it can not be found, or if the command
you specified fails in any way.  Note that the current directory and
command path are NOT preserved when starting new CLIs, so you may need to
do a CD or PATH command as part of the command executed (see NEWCLI'S
CREATED BY WICONIFY above for more details).


CLI has Trouble Finding Commands:

This is probably due to the fact that the new CLI does not inherit the
current directory or command path.  You can either specify complete path
names for the commands and files in the new CLI command, or you can
create a file containing CD, PATH and any other commands you want
performed, and have the New CLI command as EXECUTE this file.  See
NEWCLIS'S CREATED BY WICONIFY above for more detail.


wIconify Crashes with Some Programs:

wIconify has very complex interactions with Intuition and the system
as a whole.  Some programs may make assumptions about the system setup or
their screens that are no longer valid when wIconify is running.  It is even
possible that such programs will crash if wIconify is running.  If so, you
may want to use the initialization file and the IGNORE_SCREEN command to
prevent wIconify from modifying the screens used by such programs.


A Program Thinks its Window is Larger than it Really Is:

If the SIZE_TO_FIT item is checked in the OPEN_WINDOWS submenu, then
wIconify will resize windows when they open so that they fit onto the screen
where they open.  wIconify sends such programs a NEWSIZE IntuiMessage, but
not all programs are well-behaved in processing this change of size.  If you
have such a program, you may need to disable the SIZE_TO_FIT menu in order
to get it to work correctly with wIconify.


FUTURE ENHANCEMENTS:

The author feels that wIconify is pretty much complete at this point, and
that there is not too much more to be done with it.  If you have bugs or
suggestions to make, however, he would be more than happy to hear about them.


AUTHOR:

wIconify and its compaion utilities
Copyright (c) 1990,1991 by Davide P. Cervone, all rights reserved.

They were developed on 512K Amiga 1000 using Lattice C v4.0 and will
undoubtedly need some re-writting to work with Manx Aztec C.

Davide P. Cervone
Department of Mathematics
Brown University
Providence, Rhode Island  02912
ST402523@BROWNVM
[e-mail]